docs/Programming Framework.md

   1 # INAV Programming Framework
   2
   3 INAV Programming Framework (abbr. IPF) is a mechanism that allows to evaluate cenrtain flight parameters (RC channels, switches, altitude, distance, timers, other logic conditions) and use the value of evaluated expression in different places of INAV. Currently, the result of LCs can be used in:
   4
   5 * [Servo mixer](Mixer.md) to activate/deactivate certain servo mix rulers
   6 * To activate/deactivate system overrides
   7
   8 INAV Programming Framework coinsists of:
   9
  10 * Logic Conditions - each Logic Condition can be understood as a single command, a single line of code
  11 * Global Variables - variables that can store values from and for LogiC Conditions and servo mixer
  12 * Programming PID - general purpose, user configurable PID controllers
  13
  14 IPF can be edited using INAV Configurator user interface, of via CLI
  15
  16 ## Logic Conditions
  17
  18 ### CLI
  19
  20 `logic <rule> <enabled> <activatorId> <operation> <operand A type> <operand A value> <operand B type> <operand B value> <flags>`
  21
  22 * `<rule>` - ID of Logic Condition rule
  23 * `<enabled>` - `0` evaluates as disabled, `1` evaluates as enabled
  24 * `<activatorId>` - the ID of _LogicCondition_ used to activate this _Condition_. _Logic Condition_ will be evaluated only then Activator evaluates as `true`. `-1` evaluates as `true`
  25 * `<operation>` - See `Operations` paragraph
  26 * `<operand A type>` - See `Operands` paragraph
  27 * `<operand A value>` - See `Operands` paragraph
  28 * `<operand B type>` - See `Operands` paragraph
  29 * `<operand B value>` - See `Operands` paragraph
  30 * `<flags>` - See `Flags` paragraph
  31
  32 ### Operations
  33
  34 | Operation ID  | Name      | Notes                                 |
  35 |----           |----       |----                                   |
  36 | 0             | TRUE      | Always evaluates as true              |
  37 | 1             | EQUAL     | Evaluates `false` if `false` or `0`   |
  38 | 2             | GREATER_THAN  |                                   |
  39 | 3             | LOWER_THAN    |                                   |
  40 | 4             | LOW           | `true` if `<1333`                 |
  41 | 5             | MID           | `true` if `>=1333 and <=1666`     |
  42 | 6             | HIGH          | `true` if `>1666`                 |
  43 | 7             | AND           |                                   |
  44 | 8             | OR            |                                   |
  45 | 9             | XOR           |                                   |
  46 | 10            | NAND          |                                   |
  47 | 11            | NOR           |                                   |
  48 | 12            | NOT           |                                   |
  49 | 13            | STICKY        | `Operand A` is activation operator, `Operand B` is deactivation operator. After activation, operator will return `true` until Operand B is evaluated as `true`|
  50 | 14            | ADD           | Add `Operand A` to `Operand B` and returns the result |
  51 | 15            | SUB           | Substract `Operand B` from `Operand A` and returns the result |
  52 | 16            | MUL           | Multiply `Operand A` by `Operand B` and returns the result |
  53 | 17            | DIV           | Divide `Operand A` by `Operand B` and returns the result |
  54 | 18            | GVAR SET      | Store value from `Operand B` into the Global Variable addressed by `Operand B`. Bear in mind, that operand `Global Variable` means: Value stored in Global Variable of an index! To store in GVAR 1 use `Value 1` not `Global Variable 1` |
  55 | 19            | GVAR INC      | Increase the GVAR indexed by `Operand A` with value from `Operand B`  |
  56 | 20            | GVAR DEC      | Decrease the GVAR indexed by `Operand A` with value from `Operand B`  |
  57 | 21            | IO PORT SET   | Set I2C IO Expander pin `Operand A` to value of `Operand B`. `Operand A` accepts values `0-7` and `Operand B` accepts `0` and `1` |
  58 | 22            | OVERRIDE_ARMING_SAFETY        | Allows to arm on any angle even without GPS fix              |
  59 | 23            | OVERRIDE_THROTTLE_SCALE       | Override throttle scale to the value defined by operand. Operand type `0` and value `50` means throttle will be scaled by 50%. |
  60 | 24            | SWAP_ROLL_YAW                 | basically, when activated, yaw stick will control roll and roll stick will control yaw. Required for tail-sitters VTOL during vertical-horizonral transition when body frame changes |
  61 | 25            | SET_VTX_POWER_LEVEL           | Sets VTX power level. Accepted values are `0-3` for SmartAudio and `0-4` for Tramp protocol |
  62 | 26            | INVERT_ROLL                   | Inverts ROLL axis input for PID/PIFF controller |
  63 | 27            | INVERT_PITCH                  | Inverts PITCH axis input for PID/PIFF controller  |
  64 | 28            | INVERT_YAW                    | Inverts YAW axis input for PID/PIFF controller |
  65 | 29            | OVERRIDE_THROTTLE             | Override throttle value that is fed to the motors by mixer. Operand is scaled in us. `1000` means throttle cut, `1500` means half throttle |
  66 | 30            | SET_VTX_BAND                  | Sets VTX band. Accepted values are `1-5` |
  67 | 31            | SET_VTX_CHANNEL               | Sets VTX channel. Accepted values are `1-8` |
  68 | 32            | SET_OSD_LAYOUT                | Sets OSD layout. Accepted values are `0-3` |
  69 | 33            | SIN                | Computes SIN of `Operand A` value in degrees. Output is multiplied by `Operand B` value. If `Operand B` is `0`, result is multiplied by `500` |
  70 | 34            | COS                | Computes COS of `Operand A` value in degrees. Output is multiplied by `Operand B` value. If `Operand B` is `0`, result is multiplied by `500` |
  71 | 35            | TAN                | Computes TAN of `Operand A` value in degrees. Output is multiplied by `Operand B` value. If `Operand B` is `0`, result is multiplied by `500` |
  72 | 36            | MAP_INPUT          | Scales `Operand A` from [`0` : `Operand B`] to [`0` : `1000`]. Note: input will be constrained and then scaled |
  73 | 37            | MAP_OUTPUT         | Scales `Operand A` from [`0` : `1000`] to [`0` : `Operand B`]. Note: input will be constrained and then scaled |
  74 | 38            | RC_CHANNEL_OVERRIDE | Overrides channel set by `Operand A` to value of `Operand B` |
  75 | 39            | SET_HEADING_TARGET  | Sets heading-hold target to `Operand A`, in degrees. Value wraps-around. |
  76 | 40            | MOD           | Divide `Operand A` by `Operand B` and returns the remainder |
  77
  78
  79 ### Operands
  80
  81 | Operand Type  | Name      | Notes                                 |
  82 |----           |----       |----                                   |
  83 | 0             | VALUE     | Value derived from `value` field      |
  84 | 1             | GET_RC_CHANNEL    | `value` points to RC channel number, indexed from 1   |
  85 | 2             | FLIGHT        | `value` points to flight parameter table              |
  86 | 3             | FLIGHT_MODE   | `value` points to flight modes table                  |
  87 | 4             | LC            | `value` points to other logic condition ID            |
  88 | 5             | GVAR          | Value stored in Global Variable indexed by `value`. `GVAR 1` means: value in GVAR 1 |
  89 | 5             | PID          | Output of a Programming PID indexed by `value`. `PID 1` means: value in PID 1 |
  90
  91 #### FLIGHT
  92
  93 | Operand Value | Name          | Notes                                 |
  94 |----           |----           |----                                   |
  95 | 0             | ARM_TIMER     | in `seconds`                          |
  96 | 1             | HOME_DISTANCE | in `meters`                           |
  97 | 2             | TRIP_DISTANCE | in `meters`                           |
  98 | 3             | RSSI          |                                       |
  99 | 4             | VBAT          | in `Volts * 100`, eg. `12.1V` is `1210` |
 100 | 5             | CELL_VOLTAGE  | in `Volts * 100`, eg. `12.1V` is `1210` |
 101 | 6             | CURRENT       | in `Amps * 100`, eg. `9A` is `900`    |
 102 | 7             | MAH_DRAWN     | in `mAh`                              |
 103 | 8             | GPS_SATS      |                                       |
 104 | 9             | GROUD_SPEED   | in `cm/s`                             |
 105 | 10            | 3D_SPEED      | in `cm/s`                             |
 106 | 11            | AIR_SPEED     | in `cm/s`                             |
 107 | 12            | ALTITUDE      | in `cm`                               |
 108 | 13            | VERTICAL_SPEED |  in `cm/s`                           |
 109 | 14            | TROTTLE_POS   | in `%`                                |
 110 | 15            | ATTITUDE_ROLL | in `degrees`                          |
 111 | 16            | ATTITUDE_PITCH | in `degrees`                         |
 112 | 17            | IS_ARMED              | boolean `0`/`1`               |
 113 | 18            | IS_AUTOLAUNCH         | boolean `0`/`1`               |
 114 | 19            | IS_ALTITUDE_CONTROL   | boolean `0`/`1`               |
 115 | 20            | IS_POSITION_CONTROL   | boolean `0`/`1`               |
 116 | 21            | IS_EMERGENCY_LANDING  | boolean `0`/`1`               |
 117 | 22            | IS_RTH                | boolean `0`/`1`               |
 118 | 23            | IS_WP                 | boolean `0`/`1`               |
 119 | 24            | IS_LANDING            | boolean `0`/`1`               |
 120 | 25            | IS_FAILSAFE           | boolean `0`/`1`               |
 121 | 26            | STABILIZED_ROLL       | Roll PID controller output `[-500:500]`   |
 122 | 27            | STABILIZED_PITCH      | Pitch PID controller output `[-500:500]`  |
 123 | 28            | STABILIZED_YAW        | Yaw PID controller output `[-500:500]`    |
 124 | 29            | ACTIVE_WAYPOINT_INDEX | Indexed from `1`. To verify WP is in progress, use `IS_WP` |
 125 | 30            | ACTIVE_WAYPOINT_ACTION | See ACTIVE_WAYPOINT_ACTION paragraph |
 126 | 31            | 3D HOME_DISTANCE      | in `meters`, calculated from HOME_DISTANCE and ALTITUDE using Pythagorean theorem |
 127 | 32            | CROSSFIRE LQ          | Crossfire Link quality as returned by the CRSF protocol   |
 128 | 33            | CROSSFIRE SNR          | Crossfire SNR as returned by the CRSF protocol   |
 129 | 34            | GPS_VALID              | boolean `0`/`1`. True when the GPS has a valid 3D Fix                |
 130
 131 #### ACTIVE_WAYPOINT_ACTION
 132
 133 | Action        |  Value   |
 134 |----           |----      |
 135 | WAYPOINT      | 1      |
 136 | HOLD_TIME     | 3      |
 137 | RTH           | 4      |
 138 | SET_POI       | 5      |
 139 | JUMP          | 6      |
 140 | SET_HEAD      | 7      |
 141 | LAND          | 8      |
 142
 143
 144 #### FLIGHT_MODE
 145
 146 | Operand Value | Name          | Notes                                 |
 147 |----           |----           |----                                   |
 148 | 0             | FAILSAFE      |                                       |
 149 | 1             | MANUAL        |                                       |
 150 | 2             | RTH           |                                       |
 151 | 3             | POSHOLD       |                                       |
 152 | 4             | CRUISE        |                                       |
 153 | 5             | ALTHOLD       |                                       |
 154 | 6             | ANGLE         |                                       |
 155 | 7             | HORIZON       |                                       |
 156 | 8             | AIR           |                                       |
 157 | 9             | USER1         |                                       |
 158 | 10            | USER2         |                                       |
 159
 160
 161 ### Flags
 162
 163 All flags are reseted on ARM and DISARM event.
 164
 165 | bit   | Decimal   | Function              |
 166 |----   |----       |----                   |
 167 | 0     | 1         | Latch - after activation LC will stay active until LATCH flag is reseted |
 168
 169 ## Global variables
 170
 171 ### CLI
 172
 173 `gvar <index> <default value> <min> <max>`
 174
 175 ## Programming PID
 176
 177 `pid <index> <enabled> <setpoint type> <setpoint value> <measurement type> <measurement value> <P gain> <I gain> <D gain> <FF gain>`
 178
 179 * `<index>` - ID of PID Controller, starting from `0`
 180 * `<enabled>` - `0` evaluates as disabled, `1` evaluates as enabled
 181 * `<setpoint type>` - See `Operands` paragraph
 182 * `<setpoint value>` - See `Operands` paragraph
 183 * `<measurement type>` - See `Operands` paragraph
 184 * `<measurement value>` - See `Operands` paragraph
 185 * `<P gain>` - P-gain, scaled to `1/1000`
 186 * `<I gain>` - I-gain, scaled to `1/1000`
 187 * `<D gain>` - D-gain, scaled to `1/1000`
 188 * `<FF gain>` - FF-gain, scaled to `1/1000`
 189
 190 ## Examples
 191
 192 ### Dynamic THROTTLE scale
 193
 194 `logic 0 1 0 23 0 50 0 0 0`
 195
 196 Limits the THROTTLE output to 50% when Logic Condition `0` evaluates as `true`
 197
 198 ### Set VTX power level via Smart Audio
 199
 200 `logic 0 1 0 25 0 3 0 0 0`
 201
 202 Sets VTX power level to `3` when Logic Condition `0` evaluates as `true`
 203
 204 ### Invert ROLL and PITCH when rear facing camera FPV is used
 205
 206 Solves the problem from [https://github.com/iNavFlight/inav/issues/4439](https://github.com/iNavFlight/inav/issues/4439)
 207
 208 ```
 209 logic 0 1 0 26 0 0 0 0 0
 210 logic 1 1 0 27 0 0 0 0 0
 211 ```
 212
 213 Inverts ROLL and PITCH input when Logic Condition `0` evaluates as `true`. Moving Pitch stick up will cause pitch down (up for rear facing camera). Moving Roll stick right will cause roll left of a quad (right in rear facing camera)
 214
 215 ### Cut motors but keep other throttle bindings active
 216
 217 `logic 0 1 0 29 0 1000 0 0 0`
 218
 219 Sets Thhrottle output to `0%` when Logic Condition `0` evaluates as `true`
 220
 221 ### Set throttle to 50% and keep other throttle bindings active
 222
 223 `logic 0 1 0 29 0 1500 0 0 0`
 224
 225 Sets Thhrottle output to about `50%` when Logic Condition `0` evaluates as `true`
 226
 227 ### Set throttle control to different RC channel
 228
 229 `logic 0 1 0 29 1 7 0 0 0`
 230
 231 If Logic Condition `0` evaluates as `true`, motor throttle control is bound to RC channel 7 instead of throttle channel
 232
 233 ### Set VTX channel with a POT
 234
 235 Set VTX channel with a POT on the radio assigned to RC channel 6
 236
 237 ```
 238 logic 0 1 -1 15 1 6 0 1000 0
 239 logic 1 1 -1 37 4 0 0 7 0
 240 logic 2 1 -1 14 4 1 0 1 0
 241 logic 3 1 -1 31 4 2 0 0 0
 242 ```
 243
 244 Steps:
 245 1. Normalize range `[1000:2000]` to `[0:1000]` by substracting `1000`
 246 2. Scale range `[0:1000]` to `[0:7]`
 247 3. Increase range by `1` to have the range of `[1:8]`
 248 4. Assign LC#2 to VTX channel function
 249
 250 ### Set VTX power with a POT
 251
 252 Set VTX power with a POT on the radio assigned to RC channel 6. In this example we scale POT to 4 power level `[1:4]`
 253
 254 ```
 255 logic 0 1 -1 15 1 6 0 1000 0
 256 logic 1 1 -1 37 4 0 0 3 0
 257 logic 2 1 -1 14 4 1 0 1 0
 258 logic 3 1 -1 25 4 2 0 0 0
 259 ```
 260
 261 Steps:
 262 1. Normalize range [1000:2000] to [0:1000] by substracting `1000`
 263 2. Scale range [0:1000] to [0:3]
 264 3. Increase range by `1` to have the range of [1:4]
 265 4. Assign LC#2 to VTX power function